Converting Other Types of Shapes to Bitmaps (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 5 - Bitmap Shapes / Using Bitmap Shapes

Converting Other Types of Shapes to Bitmaps
The examples in the previous sections show you how to create a bitmap shape by specifying the value of every pixel in the pixel image yourself. You can also create bitmaps using one of a number of simpler methods. For example, you can convert any QuickDraw GX shape to a bitmap shape. The pixel image of the resulting bitmap shape contains a bitmap representation of the original shape. (In a similar way, when you draw a shape to a display device, the display device displays a bitmap representation of the original shape.)
To convert another type of shape into a bitmap shape, you use the GXSetShapeType function, which is described in detail in the chapter "Shape Objects" of Inside Macintosh: QuickDraw GX Objects.
Listing 5-9 shows a sample function that defines a figure-eight geometry, encapsulates the geometry in a path shape, sets the pen width of that path to 10, and skews the path around its center by 10% along both the horizontal and vertical axes. Then the sample function converts the path shape into a bitmap shape and draws the bitmap.
Listing 5-9 Converting a path to a bitmap
void ConvertPathToBitmap(void)
{
   gxShape pathToBitmapShape;

   gxRectangle theBounds;
   
   const long figureEightGeometry[] = {1, /* number of contours */
                                       4, /* number of points */
                                       0xF0000000, /* 1111 ... */
                                       ff(20), ff(20),   /* off */
                                       ff(100), ff(100), /* off */
                                       ff(20), ff(100),  /* off */
                                       ff(100), ff(20)}; /* off */
                              
   pathToBitmapShape = GXNewPaths((gxPaths *) figureEightGeometry);
   GXSetShapeFill(pathToBitmapShape, gxClosedFrameFill);
   GXSetShapePen(pathToBitmapShape, ff(10));
   GXSkewShape(pathToBitmapShape, fl(.1), fl(.1), ff(60), ff(60));
   
   GXSetShapeType(pathToBitmapShape, gxBitmapType);
   GXDrawShape(pathToBitmapShape);
   GXDisposeShape(pathToBitmapShape);
}
Listing 5-9 uses the GXSkewShape function, which is described fully in the chapter "Transform Objects" in Inside Macintosh: QuickDraw GX Objects.
Figure 5-18 shows the result of this function.
Figure 5-18 A bitmap representation of a path shape

Notice that QuickDraw GX draws the bitmap at 72 pixels per inch.
When converting shapes to bitmap shapes, QuickDraw GX creates a bitmap shape with the smallest pixel image possible to contain the bitmap representation of the original shape. To illustrate, you can draw the bounding rectangle of the skewed figure-eight bitmap by adding to Listing 5-9 the declaration
gxRectangle theBounds;
and these two lines of code:
GXGetShapeBounds(pathToBitmapShape, 0, &theBounds);
GXDrawRectangle(&theBounds, gxClosedFrameFill);
The resulting bitmap and bounding rectangle are shown in Figure 5-19.
Figure 5-19 A bitmap and its bounding rectangle

When QuickDraw GX converts other types of shapes into a bitmap shape, it creates a new bitmap geometry and draws the original shape into the bitmap's pixel image. If the original shape does not cover all of the pixels in the bitmap's pixel image, QuickDraw GX sets the color value of the extra pixels to white. These white pixels may produce unexpected results if you draw the bitmap over a background that includes colors other than white.
For example, the following code adds a background shape to the sample function in Listing 5-9:
gxShape backgroundShape;
const gxRectangle backgroundBounds = {ff(20), ff(10), 
                                      ff(100), ff(110)};

backgroundShape = GXNewRectangle(&backgroundBounds);
SetShapeCommonColor(backgroundShape, purple);
If you draw the background before the bitmap, the white pixels of the bitmap cover the corresponding area of the purple rectangle:
GXDrawShape(backgroundShape);
GXDrawShape(pathToBitmapShape);
The result appears as shown in Figure 5-20. For a color version of this figure, see Plate 6 at the front of this book.
Figure 5-20 A bitmap drawn over a background

You can set the transfer mode of the bitmap shape to allow the purple to show through the white pixels. For example, you can set the transfer mode of the bitmap to the gxMinimumMode transfer mode using this code:
SetShapeCommonTransfer(pathToBitmapShape, gxMinimumMode);
GXDrawShape(pathToBitmapShape);
The result is shown in Figure 5-21. For a color version of this figure, see Plate 6 at the front of this book.
Figure 5-21 A bitmap with a transfer mode drawn over a background

Another way to allow the purple rectangle to show through the white areas of this bitmap is to set the clip shape of the bitmap. The next section, "Applying Transformations to Bitmaps," shows an example of clipping a bitmap.
The examples in this section use colors and the SetCommonColor library function, which are available in the color library, and transfer modes and the SetShapeCommonTransfer library function, which are available in the transfer mode library.
For more information about the GXSetShapeType function, see the chapter "Shape Objects" in Inside Macintosh: QuickDraw GX Objects.
For information about combining multiple QuickDraw GX shapes into a single bitmap shape, see "Creating Bitmaps Offscreen," which begins on page 5-45.